InfoMagic Internet Tools 1995 April/Internet Tools.iso/x25/nrs.shar.Z/nrs.shar/nrs.ms

Text File | 1990-04-27 | 19.2 KB | 670 lines

.\"  RCSid[] = "@(#)$Header: nrs.ms,v 3.4 88/05/27 06:25:28 pb Rel $"
.TL
A Quick Jog Through Configuring The Nrs Processor.
.AU
Julian Onions
.AI
Computer Science Group,
Nottingham University.
.AU
Piete Brooks
.AI
University of Cambridge Computer Laboratory,
New Museum Site, Pembroke Street, CB2 3QG
.AU
Adrian Pell
.AI
Department of Computer Science,
University of Reading.
.NH
Introduction
.LP
This document describes how to build yourself a configuration
file for the nrs database cruncher, hereinafter referred to as the
.I nrs
program.
.LP
Currently the
.I nrs
program runs under
.UX
(BSD 4.2/ULTRIX 1.2 on VAX 11/750s, VAX 11/780s, Microvax IIs,
Orions and Suns;
V7/ULTRIX 11 on PDP/11s;
System V on GEC 63s), VMS (VAX VMS C 2.1 on Microvax IIs) and
PRIMOS, and can be run in one of six modes, as detailed in section 3.2,
.IP 1)
York X25 directory mode (R2.2 or R2.1)
.IP 2)
MMDF table generation mode.
.IP 3)
X25hosts directory mode (UBC code).
.IP 4)
Text mode (as per t.central, PR1ME and Edinburgh).
.IP 5)
VMS mode.
.IP 6)
Sendmail mode (UK or Reading versions).
.IP 7)
DBM mode (for unix-niftp)
.NH
The NRS Database Format
.LP
This is a brief introduction to the structure of the
NRS Database. For more details, read the NRS
document
.ul
Making and Using Derived Databases
by Dr. R.D. Baker, obtainable from the University of Salford.
.LP
The NRS Database consists of one file which is made up of the following
sections (previously separate files - these are still accepted):
.LP
A section known as
.I MODULE2 ,
which contains within it
all the long and short NRS registered hosts together with
associated pointers to the
.I MODULE4
section.
.LP
A section known as
.I MODULE3 ,
which contains information used for reverse lookups and is used
if reverse lookups are indicated.
.LP
A section known as
.I MODULE4 ,
which contains information groups of records called quads
which give the filename and offset in one of the
.I ATOMIC
sections.
.LP
A number of
.I ATOMIC
sections, one for each network-context pair.
These
.I ATOMIC
files contain the
.I DTE
address of the host,
the Yellow Book Transport Service address if any,
a list of application relays if any
and the description text (in the DESC context only).
Therefore to look up a host involves three file accesses.
.LP
The purpose of the
.I nrs
program, is to run through this data in one go, and print
it out in formats expected by other programs.
.br
NB:
The
.I nrs
program can be compiled so that only one or two output formats
are selected. This is to cut down on space and memory requirements.
If this is the case, some output specific keywords may not be
recognised.
.NH
The configuration file
.LP
.DS
nrs [<config-file>] [<options>]*
.DE
The normal use is to supply
.I nrs
with a configuration file,
however other options may be added in the same format as
the configuration file options to overide or alter the options
in the configuration file.
This behaviour is similar to the way
.I awk (1)
treats its arguments.
.LP
Within the configuration file, of which there should be some
examples with the program, there are several lines giving
control information to the nrs program.
Each line is read in turn and parsed into arguments.
Comment lines start with a hash `#' character and are
completely ignored, as are blank lines.
All other lines are examined for control information.
The control line keywords are generally case insensitive,
but where they specify values such as filenames, the filenames
must be in the right case.
Arguments are separated by white space.
.LP
.NH 2
General Control Lines
.LP
The following control lines have general use regardless
of which mode the program is to run in.
.DS
directory <directory-name>
.DE
This gives a directory name to prepend to all input file names,
thus enabling the data to be separated from the results.
On
.UX
a / is inserted between the directory and the filename,
and the directory parameter if present can be overridden for a
particular file by either giving the full pathname, or a
relative pathname (one starting ./ or ../).
On
VMS
the filename is directly suffixed to the directory name, but the directory is
ignored if the pathname contains a colon (:), a dollar ($) or an open square
bracket ([).
On PR1MEs a ket (>) is inserted between the directory and the filename,
unless the file name contains a ket (>), in which case it is used directly.
.DS
derfil  <filename>
.DE
This control line sets up the name of the NRS derived file for the
.I nrs
program. If this line are missing, the filename will default to
DERFIL2
.DS
domains  [<filename>]
.DE
This control line instructs the processor to include the domain gateway
information if the format supports it.
The filename is needed only if it is processing filettes.
A destination file for the output should be given, i.e.
.DS
filedmn top.dmn -top.dmn-
.DE
where the special name -top.dmn- is used for mmdf and -top.dom- for sendmail.
.DS
filedmn <file-name> [<short-dmn-name> [<long-dmn-name> [local]]]
.DE
These are used by mmdf and sendmail formats to specify where domain table
information is to be written for specified sub-domains.
If no long domain name is given it is assumed to be identical to the short
domain name.
If no short domain name is given,
then the short domain is set to a state where it matches all domains,
so this acts as a catch all.
As these tables are scanned in the order,
the order in which they appear is critical.
To show how these fields work, an example of how the nottingham
setup is configured.
.DS
.ta \w'filedmn uk-ac-nott-dmn  'u +\w'uk.ac.nott.  'u
filedmn uk-ac-nott-dmn  uk.ac.nott. uk.ac.nottingham.
filedmn uk-ac-dmn    uk.ac.
filedmn uk-co-dmn    uk.co.
filedmn cern-dmn    cern.
filedmn desy-dmn    desy.
filedmn top-dmn    -top.dmn-
filedmn misc-dmn
.DE
.TA
This specifies that having got an address, it is run down the
list of preferred domains (as set by
.I short/long
)
to see if any are a prefix. The last
line catches anything unmatched.
So with a host such as
.DS
.ta \w'uk.ac.nott.cs 'u
short        long
uk.ac.nott.cs    uk.ac.nottingham.computer-science
.DE
There is a match in the first line as uk.ac.nott. is a prefix.
This is then marked as a hit and the long and short domains
stripped off to give
.DS
.ta \w'uk.ac.nott.cs 'u
short    long
cs    computer-science
.DE
These are then put into the uk-ac-nott-dmn file as
.DS
cs:computer-science.nottingham.ac.uk
computer-science:computer-science.nottingham.ac.uk
.DE
With a host such as uk.ac.ucl.cs, the first hit is in the uk.ac. entry so the
result is put into the uk-ac-dmn file.
If the host has application relays, these are listed after
the entry as relays.
If the local flags is given, any application relays are supressed.
.PP
Mmdf and sendmail have special domains, -top.dmn- and -top.dom- respectively,
to which the NRS gateway information is sent, e.g. the fact that mail to MIL.
goes via uk.ac.ucl.cs.
Sendmail also has the special domain -abbrev.dom- which is where the aliases
between long and short forms are put.
.DS
filechan <filename> <network> [<prefix>]
.DE
Channel tables may also be built whilst constructing the domain tables.
After putting the name into a domain table, the host is looked up in the list
of networks attached to the filechan control.
If a match is found, it is put into the associated filename.
A typical setup is
.DS
filechan pss-chan    pss
filechan janet-chan    janet
.DE
The optional third argument, used only for MMDF, will cause that prefix to be
stripped off on the RHS of the channel table.
E.g.
.DS
filechan janet-chan janet uk.ac.
.DE
will result in entries of the form
.DS
name.host.ac.uk:host.name
.DE
which may help match up with entries in your x25 directory.
For sendmail UK-1.4, channel table entries are only constructed for mail sites
which need applicatiom relays.
.LP
.DS
gateway [pss|janet] <gatewayhost>
.DE
This is used by both york formats and smail format to specify a gateway host
to a particular network.
.DS
relay_host <hostname>
.DE
If this is present for MMDF format, then entries are matched in the list of
domains as before, but have added after their entry the hostname
specified in the relay_host line.
This is so that if the host you are building the table for is not actually
connected to the network directly, all hosts may be relayed
through another host first to reach the network.
E.g.
.DS
relay_host hcig.nott.ac.uk
.DE
would alter the above case of ucl.cs to
.DS
cs.ucl:cs.ucl.ac.uk hcig.nott.ac.uk
.DE
Any application relays in this case are thrown away. It is
presumed that the relay host will know the best route from then on.
Sendmail UK-1.4 used a uk entry in top.dom to do off-janet sites.
.LP
However to stop spurious entries such as
.DS
ourname:ourname.ourdomain.ac.uk relayhost
.DE
which is an infinite loop, the local keyword is attached to a
domain which suppresses the relayhost for those entries.
.DS
verbose [<number>]
.DE
This parameter sets the level of information messages produced to number
(or one if missing).
If no
.I verbose
control line is present,
or the verbose setting is 0,
only fatal errors and warning messages
will be given.
.DS
context <context> <network>
.DE
This control line specifies to the
.I nrs
program that the
.I ATOMIC
section for the given context and the given
network should be used.
The context parameter may be any of the following keywords.
.IP X29 14
Remote login to an interactive service using X29.
.IP TS29 14
Remote login to an interactive service using TS29.
.IP NIFTP 14
File access to some filestore using NIFTP protocol.
.IP FTP 14
A synonym for above
.IP MAIL-NIFTP 14
Electronic mail to an individual in some organisation,
using Grey Book Mail protocol over NIFTP.
.IP MAIL 14
A synonym for above.
.IP MAIL-X29 14
Electronic mail over X29 connections.
.\" bluff bluff bluff - I'm not sure what this is really.
.IP MAIL-TELEX 14
Electronic mail to Telex Machines
.\" I hope!
.IP JTMP 14
Job Transfer and Manipulation Protocol for running jobs
and printing output.
.IP JTMP-FILES 14
File store references with in JTMP descriptors (whatever that means!).
.IP JTMP-REG 14
Registration authorities referenced within JTMP descriptors (ditto).
.IP YBTS-NODE 14
Yellow Book Transport Service locations (???)
.IP YBTS 14
Yellow Book Transport service interprocess connections (???)
.IP DESC 14
The Description Text for the host.
.IP
.LP
A complete set of contexts
and networks should be found in the york configuration
file supplied as an example.
.LP
The network keyword is currently one of
.IP JANET 14
The Joint Academic network.
.IP PSS 14
The British Telecom Packet Switched network.
.IP TELEX 14
The Telex network.
.LP
Often, for a particular type of output, you are only interested
in certain combinations of contexts and networks, for instance
mmdf is only interested in mail addresses, so most of the contexts
are redundant and shouldn't be included.
.DS
file <filename> <context> <network>
module2 <filename>
module3 <filename>
module4 <filename>
.DE
These are used for the old filettes format (do not use these - use DERFIL2).
They map a section onto a filename.
.NH 2
Output specific control lines.
.LP
The output format is specified by the output keyword which takes optional
flags indicating a preference for long or short names, the desired mapping as
forward or reverse and the desired case of the output.
After this may come the mode and any mode specific options.
.DS
output [long|short] [forward|reverse] [mixed|lower] [<mode> [<option>]*]
.DE
Several of the modes have a `preferred' mapping (i.e. long or short);
in mmdf mode it determines which form appears first in the tables,
the form of the RHS of the domain table and the form of the channel table;
in sendmail mode it specifies which is the main name, and which is the alias.
If there are no explicit instructions for the requied format,
do not quote either form.
.LP
Normally the sequence is to scan through the MODULE2 section,
reading each record in turn and looking up the values in the
other sections.
This behaviour gives the forward lookup type tables.
If reverse is set, then the MODULE3 section is read in a record at a time and the
various records from other sections are collected.
This sort of processing gives reverse lookup type tables,
and is currently only generally useful with york and text format output.
.LP
The case of the produced output can be selected by use of the
.I mixed/lower
flags which leave the case as it is (usually UPPER CASE), or force it to lower
case.
.NH 3
York Format Output
.LP
.DS
output york
output york2.1 [<prefix>]
.DE
The optional second parameter represents a prefix string to strip off all
names and is applicable only to the older format (R2.1) directory format.
This format should not be used as it is highly deficient.
.DS
output york2.1 uk.ac.
.DE
makes uk.ac.cam.cl appear as cam.cl.
With D2.2 the directory contains the full names, and the stripping is done
much more cleverly by the programme which created the DBM file.
.IP \fIforward/reverse\fR 16
indicate the direction of the mapping.
.LP
.DS
gateway <network> <string>
.DE
Gateway is used if you have to go through a gateway to get to a network.
The network argument may be pss or janet.
The string is prefixed to any DTE on the specified network.
E.g.
.DS
Gateway PSS 000000002105/
.DE
produces lines of the form
.DS
0:PSS:X:psshost:000000002105/000012345678:
.DE
.NH 3
MMDF format output
.LP
This is rather more complicated than the york format, but
with an example config file it shouldn't be too hard ...
.IP \fIshort/long\fR 16
indicates whether to generate an mmdf domain table
mapping short to long addresses, or long to short address.
.LP
The output in mmdf format is set up by the control line
.DS
output mmdf
.DE
The hard part comes in working out what domains your interested
in and what to do with them - see filedmn for domain tables
and filechan for channel tables.
.NH 3
x25hosts format output
.LP
This format is useful if you are in need of an /etc/hosts
type of format. It only lists entries without application relays or yellow
book transport service strings. This is currently only used by the UBC X25
software but may be used by other 4.2 networking code in the future.
.LP
It is enabled by the line
.DS
output x25hosts [<prefix>]
.DE
The optional second argument is assumed to be a prefix to strip off the
entries.
The output format is
.DS
dteaddr [stripped-form] short-form long-form
.DE
Addresses with application relays are discarded.
.NH 3
Text format output
.LP
.IP \fIforward/reverse\fR 16
should be set as appropriate.
.IP \fIshort/long\fR 16
selects the format in which the name is to be printed.
The default is to print both.
.LP
.DS
output text
.DE
.LP
The output is in `human readable' format.
This is in a similar style to the NRS `t.central' format.
.NH 3
VMS format output
.LP
.DS
output [ignorerelay] vms
.DE
.LP
The output is in a format for feeding into NETAUTH, one of the programmes in
the "Coloured Books" package written by UWIST and St Andrews and marketed by
DEC which runs over PSI.
The standard header actually generates a DCL command file.
This produces optimised commands to process all names of less than 33
characters (a limitation applied by NETAUTH) of the form
.DS
D nrsname
A nrsname+=commonDTEprefix+context1=suffix1+context2=suffix2
.DE
It puts quotes wherever there are any suspect characters,
arranges for the context with a null suffix to appear at the end,
handles different DTEs for the same name, etc. etc..
.br
However, the algorithms were worked out by guess work so may need fixing.
.br
NETAUTH cannot make any use of application relays, so if the programme is
being used as an NRS table generator, then these entries are omitted.
However, if it is being used as a GreyBook table generator, it is permissable
to omit the application relays, so the flag
.B ignorerelay
can be given, and the entries will be generated with the application relays
doscarded.
.NH 3
Sendmail and Smail format output
.LP
.IP \fIshort/long\fR 16
should be set as appropriate for sendmail (ignored by smail).
.LP
.DS
output sendmail
output smail
.DE
.LP
The output is for processing by Jim Crammond's UK Sendmail package,
or Reading's smail.
The sendmail info is based upon mmdf's domain and channel tables
(see mmdf mode)
.NH 3
DBM (unix-niftp) format output
.LP
.IP \fIforward/reverse\fR 16
should be set as appropriate.
.IP \fIshort/long\fR 16
indicates whether the long or short form is the primary key.
.LP
.DS
output dbm
.DE
.LP
The output is in a format for feeding into dbmencode after optional editing of
fields not supplied by the NRS.
.NH 3
PR1ME text format output
.LP
.IP \fIforward/reverse\fR 16
should be set as appropriate.
.LP
.DS
output prime
.DE
.LP
The output is in a format used on PR1ME systems, and is very similar to
t.central.
.NH 3
Edinburgh text format output
.LP
.DS
output edtext [simple|short|long]
.DE
.LP
The output is in a text format devised in Edinburgh, much preferable to
t.central.
If short and/or long is specified every line is to be prefixed with the
relevant name, e.g. to allow a simple search to return the useful information.
If no flag is given, short is used (simple implies no names).
.LP
This format is intended to dump the ENTIRE database, so ALL contexts should be
requested.
If this is not done, a warning is generated when the first missing context is
processed.
.NH
Supplemental commands
.LP
.DS
comment <filename>
.DE
will cause the contents of the file given to be filtered through a small macro
expander which replaces certain keys with values rather like RCS keywords,
when writing to an output for the first time.
This helps keep files in sync across several machines.
At present the following keys are expanded:
.IP $C$
This expands to some text relevant to the output type.
.IP $D$
The current date and time in ctime(3) format.
.IP $F$
The current file name.
.IP $H$
The hostname of this host. This may be set with the
control
.I "hostname string"
(see below).
.IP $N$
The Version of the NRS database used in building this file.
This information is gleaned from the database headers.
.LP
.DS
hostname <name>
.DE
specifies the hostname for the comment field $H$.
This overrides the name returned by the gethostname (BSD) or
uname (USG) call.
.NH
Error messages.
.LP
Most error messages are hopefully self explanatory,
but a few could bear further explanation.
.DS
lru botch - can't reclaim an lru file descriptor.
problem on getm2rec rec %d - bad format MODULE2 section
Can't find corresponding short entry for %s
    - again a bad format MODULE2 section
problem on getm4rec rec %d - bad format MODULE4 section
already got a dte - a host has more than one dte address
already got a yb - a host has more than one ybts string
unknown line, '%s' '%s' - bad format atomic file
Files are out of sync - the atomic files + the modules files
        are not all from the same run of the salford
        database - reget the atomic + modules files.
.DE
.NH
Problems
.LP
No doubt there will be problems ...
if so you can contact any of us at:
.DS
Email Addresses:

[e-mail] ([e-mail]-science)
[e-mail] ([e-mail])

[e-mail] ([e-mail]-lab)
cam-cl.uucp!pb (...mcvax!ukc!cam-cl!pb)

[e-mail]
.DE
Alternatively if you're really stuck try
.DS
Snail Mail:

Julian Onions
Computer Science Group,
Nottingham University
University Park,
Nottingham
NG7 2RD
([phone] x3595

Piete Brooks
Computer Laboratory,
New Museum Site,
Pembroke Street,
Cambridge
CB2 3QG
([phone] (DDI)

Adrian Pell
Dept. of Computer Science
University of Reading
PO Box 220
Reading
RG6 2AX
([phone] x 411
.DE